package com.smart.community.work.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.work.entity.SecurityRoute;
import com.smart.community.work.entity.SecurityPatrol;
import com.smart.community.work.entity.SecurityEvent;
import com.smart.community.work.entity.Visitor;
import com.smart.community.work.vo.SecurityRouteVO;
import com.smart.community.work.vo.SecurityPatrolVO;
import com.smart.community.work.vo.SecurityEventVO;
import com.smart.community.work.vo.VisitorVO;
import com.smart.community.work.dto.SecurityRouteQueryDTO;
import com.smart.community.work.dto.SecurityRouteCreateDTO;
import com.smart.community.work.dto.SecurityRouteUpdateDTO;
import com.smart.community.work.dto.SecurityPatrolQueryDTO;
import com.smart.community.work.dto.SecurityEventQueryDTO;
import com.smart.community.work.dto.VisitorQueryDTO;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;

/**
 * 安保管理服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范_重构版.md》Service规范实现：
 * - 继承IService：获得基础CRUD方法
 * - 方法命名：使用动词+名词形式，语义明确
 * - 参数验证：使用@Valid注解进行参数验证
 * - 异常处理：使用统一的异常处理机制
 * - 完整注释：所有方法都有完整的JavaDoc注释
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 * @version 1.0.0
 */
public interface SecurityService extends IService<SecurityRoute> {

    // ========================= 巡逻路线管理 =========================

    /**
     * 分页查询巡逻路线
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数DTO
     * @return 巡逻路线分页数据
     * @throws Exception 异常
     */
    IPage<SecurityRouteVO> selectSecurityRoutePage(Page<SecurityRouteVO> page, SecurityRouteQueryDTO queryDTO) throws Exception;

    /**
     * 分页查询巡逻路线（带权限控制）
     * 根据用户数据权限获取有权限的社区ID列表，然后查询对应的安保路线数据
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数DTO
     * @param currentUserId 当前用户ID
     * @return 巡逻路线分页数据
     * @throws Exception 异常
     */
    IPage<SecurityRouteVO> selectSecurityRoutePageWithPermission(Page<SecurityRouteVO> page, SecurityRouteQueryDTO queryDTO, Long currentUserId) throws Exception;

    /**
     * 根据ID查询巡逻路线详情
     * 
     * @param id 路线ID
     * @return 巡逻路线详情
     * @throws Exception 异常
     */
    SecurityRouteVO selectSecurityRouteById(Long id) throws Exception;

    /**
     * 创建巡逻路线
     * 
     * @param createDTO 巡逻路线创建DTO
     * @return 创建结果
     * @throws Exception 异常
     */
    Boolean createSecurityRoute(SecurityRouteCreateDTO createDTO) throws Exception;

    /**
     * 更新巡逻路线
     * 
     * @param updateDTO 巡逻路线更新DTO
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateSecurityRoute(SecurityRouteUpdateDTO updateDTO) throws Exception;

    /**
     * 删除巡逻路线
     * 
     * @param id 路线ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteSecurityRoute(Long id, Long updateBy) throws Exception;

    // ========================= 巡逻记录管理 =========================

    /**
     * 分页查询巡逻记录
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数DTO
     * @return 巡逻记录分页数据
     * @throws Exception 异常
     */
    IPage<SecurityPatrolVO> selectSecurityPatrolPage(Page<SecurityPatrolVO> page, SecurityPatrolQueryDTO queryDTO) throws Exception;

    /**
     * 根据用户ID查询巡逻记录
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 巡逻记录列表
     * @throws Exception 异常
     */
    List<SecurityPatrolVO> selectSecurityPatrolByUserId(Long userId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 开始巡逻
     * 
     * @param securityPatrol 巡逻记录信息
     * @return 开始结果
     * @throws Exception 异常
     */
    Boolean startPatrol(SecurityPatrol securityPatrol) throws Exception;

    /**
     * 巡逻签到
     * 
     * @param patrolId 巡逻记录ID
     * @param checkPointId 签到点ID
     * @param checkTime 签到时间
     * @param remark 签到备注
     * @return 签到结果
     * @throws Exception 异常
     */
    Boolean patrolCheckIn(Long patrolId, Long checkPointId, LocalDateTime checkTime, String remark) throws Exception;

    /**
     * 结束巡逻
     * 
     * @param patrolId 巡逻记录ID
     * @param endTime 结束时间
     * @param summary 巡逻总结
     * @return 结束结果
     * @throws Exception 异常
     */
    Boolean endPatrol(Long patrolId, LocalDateTime endTime, String summary) throws Exception;

    /**
     * 更新巡逻记录
     * 
     * @param securityPatrol 巡逻记录信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateSecurityPatrol(SecurityPatrol securityPatrol) throws Exception;

    /**
     * 删除巡逻记录
     * 
     * @param id 记录ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteSecurityPatrol(Long id, Long updateBy) throws Exception;

    // ========================= 安全事件管理 =========================

    /**
     * 分页查询安全事件
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数DTO
     * @return 安全事件分页数据
     * @throws Exception 异常
     */
    IPage<SecurityEventVO> selectSecurityEventPage(Page<SecurityEventVO> page, SecurityEventQueryDTO queryDTO) throws Exception;

    /**
     * 根据ID查询安全事件详情
     * 
     * @param id 事件ID
     * @return 安全事件详情
     * @throws Exception 异常
     */
    SecurityEventVO selectSecurityEventById(Long id) throws Exception;

    /**
     * 上报安全事件
     * 
     * @param securityEvent 安全事件信息
     * @return 上报结果
     * @throws Exception 异常
     */
    Boolean reportSecurityEvent(SecurityEvent securityEvent) throws Exception;

    /**
     * 处理安全事件
     * 
     * @param eventId 事件ID
     * @param handlerId 处理人ID
     * @param handleResult 处理结果
     * @param handleRemark 处理备注
     * @return 处理结果
     * @throws Exception 异常
     */
    Boolean handleSecurityEvent(Long eventId, Long handlerId, String handleResult, String handleRemark) throws Exception;

    /**
     * 更新安全事件
     * 
     * @param securityEvent 安全事件信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateSecurityEvent(SecurityEvent securityEvent) throws Exception;

    /**
     * 删除安全事件
     * 
     * @param id 事件ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteSecurityEvent(Long id, Long updateBy) throws Exception;

    // ========================= 访客管理 =========================

    /**
     * 分页查询访客记录
     * 
     * @param page 分页参数
     * @param queryDTO 查询参数DTO
     * @return 访客记录分页数据
     * @throws Exception 异常
     */
    IPage<VisitorVO> selectVisitorPage(Page<VisitorVO> page, VisitorQueryDTO queryDTO) throws Exception;

    /**
     * 根据ID查询访客记录详情
     * 
     * @param id 访客记录ID
     * @return 访客记录详情
     * @throws Exception 异常
     */
    VisitorVO selectVisitorById(Long id) throws Exception;

    /**
     * 访客登记
     * 
     * @param visitor 访客信息
     * @return 登记结果
     * @throws Exception 异常
     */
    Boolean registerVisitor(Visitor visitor) throws Exception;

    /**
     * 访客离开
     * 
     * @param visitorId 访客记录ID
     * @param leaveTime 离开时间
     * @return 离开结果
     * @throws Exception 异常
     */
    Boolean visitorLeave(Long visitorId, LocalDateTime leaveTime) throws Exception;

    /**
     * 更新访客记录
     * 
     * @param visitor 访客信息
     * @return 更新结果
     * @throws Exception 异常
     */
    Boolean updateVisitor(Visitor visitor) throws Exception;

    /**
     * 删除访客记录
     * 
     * @param id 访客记录ID
     * @param updateBy 更新人ID
     * @return 删除结果
     * @throws Exception 异常
     */
    Boolean deleteVisitor(Long id, Long updateBy) throws Exception;

    // ========================= 统计查询 =========================

    /**
     * 获取安保统计信息
     * 
     * @param propertyCompanyId 物业公司ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 统计信息
     * @throws Exception 异常
     */
    Map<String, Object> getSecurityStatistics(Long propertyCompanyId, LocalDate startDate, LocalDate endDate) throws Exception;

    /**
     * 获取用户安保统计
     * 
     * @param userId 用户ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 用户统计信息
     * @throws Exception 异常
     */
    Map<String, Object> getUserSecurityStatistics(Long userId, LocalDate startDate, LocalDate endDate) throws Exception;
}
